'\" t
.\"     Title: coap_handler
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 12/27/2024
.\"    Manual: libcoap Manual
.\"    Source: coap_handler 4.2.0
.\"  Language: English
.\"
.TH "COAP_HANDLER" "3" "12/27/2024" "coap_handler 4\&.2\&.0" "libcoap Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
coap_handler, coap_register_handler, coap_register_response_handler, coap_register_nack_handler, coap_register_ping_handler, coap_register_pong_handler, coap_register_event_handler \- work with CoAP handlers
.SH "SYNOPSIS"
.sp
\fB#include <coap2/coap\&.h>\fR
.sp
\fBvoid coap_register_handler(coap_resource_t *\fR\fB\fIresource\fR\fR\fB, unsigned char \fR\fB\fImethod\fR\fR\fB, coap_method_handler_t \fR\fB\fIhandler\fR\fR\fB);\fR
.sp
\fBvoid coap_register_response_handler(coap_context_t *\fR\fB\fIcontext\fR\fR\fB, coap_response_handler_t \fR\fB\fIhandler\fR\fR\fB)\fR;
.sp
\fBvoid coap_register_nack_handler(coap_context_t *\fR\fB\fIcontext\fR\fR\fB, coap_nack_handler_t \fR\fB\fIhandler\fR\fR\fB)\fR;
.sp
\fBvoid coap_register_ping_handler(coap_context_t *\fR\fB\fIcontext\fR\fR\fB, coap_ping_handler_t \fR\fB\fIhandler\fR\fR\fB)\fR;
.sp
\fBvoid coap_register_pong_handler(coap_context_t *\fR\fB\fIcontext\fR\fR\fB, coap_pong_handler_t \fR\fB\fIhandler\fR\fR\fB)\fR;
.sp
\fBvoid coap_register_event_handler(coap_context_t *\fR\fB\fIcontext\fR\fR\fB, coap_event_handler_t \fR\fB\fIhandler\fR\fR\fB)\fR;
.sp
Link with \fB\-lcoap\-2\fR, \fB\-lcoap\-2\-gnutls\fR, \fB\-lcoap\-2\-openssl\fR or \fB\-lcoap\-2\-tinydtls\fR depending on your (D)TLS library type\&.
.SH "DESCRIPTION"
.sp
The \fBcoap_register_handler\fR() function registers a callback handler \fIhandler\fR that is called when there is a URI match against the \fIresource\fR and there is a \fImethod\fR (e\&.g\&. PUT, POST etc\&.) match\&. \fImethod\fR can be one of the following\&.
.sp
.if n \{\
.RS 4
.\}
.nf
COAP_REQUEST_GET
COAP_REQUEST_POST
COAP_REQUEST_PUT
COAP_REQUEST_DELETE
COAP_REQUEST_FETCH
COAP_REQUEST_PATCH
COAP_REQUEST_IPATCH
.fi
.if n \{\
.RE
.\}
.sp
The handler function prototype is defined as:
.sp
.if n \{\
.RS 4
.\}
.nf
typedef void (*coap_method_handler_t)(coap_context_t *context,
                                      coap_resource_t *resource,
                                      coap_session_t *session,
                                      coap_pdu_t *incoming_pdu,
                                      coap_string_t *token,
                                      coap_string_t *query,
                                      coap_pdu_t *response_pdu);
.fi
.if n \{\
.RE
.\}
.sp
The \fBcoap_register_response_handler\fR() function defines a request\(cqs response \fIhandler\fR for traffic associated with the \fIcontext\fR\&. The application can use this for handling any response packets, including sending a RST packet if this response was unexpected\&. If \fIhandler\fR is NULL, then the handler is de\-registered\&.
.sp
The handler function prototype is defined as:
.sp
.if n \{\
.RS 4
.\}
.nf
typedef void (*coap_response_handler_t)(coap_context_t *context,
                                        coap_session_t *session,
                                        coap_pdu_t *sent,
                                        coap_pdu_t *received,
                                        const coap_tid_t id);
.fi
.if n \{\
.RE
.\}
.sp
The \fBcoap_register_nack_handler\fR() function defines a request\(cqs negative response \fIhandler\fR for traffic associated with the \fIcontext\fR\&. If \fIhandler\fR is NULL, then the handler is de\-registered\&.
.sp
The handler function prototype is defined as:
.sp
.if n \{\
.RS 4
.\}
.nf
typedef void (*coap_nack_handler_t)(coap_context_t *context,
                                    coap_session_t *session,
                                    coap_pdu_t *sent,
                                    coap_nack_reason_t reason,
                                    const coap_tid_t id);
.fi
.if n \{\
.RE
.\}
.sp
The \fBcoap_register_ping_handler\fR() function defines a \fIhandler\fR for tracking CoAP ping traffic associated with the \fIcontext\fR\&. If \fIhandler\fR is NULL, then the handler is de\-registered\&.
.sp
The handler function prototype is defined as:
.sp
.if n \{\
.RS 4
.\}
.nf
typedef void (*coap_ping_handler_t)(coap_context_t *context,
                                    coap_session_t *session,
                                    coap_pdu_t *received,
                                    const coap_tid_t id);
.fi
.if n \{\
.RE
.\}
.sp
The \fBcoap_register_pong_handler\fR() function defines a \fIhandler\fR for tracking CoAP TCP ping response traffic associated with the \fIcontext\fR\&. If \fIhandler\fR is NULL, then the handler is de\-registered\&.
.sp
The handler function prototype is defined as:
.sp
.if n \{\
.RS 4
.\}
.nf
typedef void (*coap_pong_handler_t)(coap_context_t *context,
                                    coap_session_t *session,
                                    coap_pdu_t *received,
                                    const coap_tid_t id);
.fi
.if n \{\
.RE
.\}
.sp
The \fBcoap_register_event_handler\fR() function defines a \fIhandler\fR for tracking (D)TLS events associated with the \fIcontext\fR\&. If \fIhandler\fR is NULL, then the handler is de\-registered\&.
.sp
The handler function prototype is defined as:
.sp
.if n \{\
.RS 4
.\}
.nf
typedef void (*coap_event_handler_t)(coap_context_t *context,
                                     coap_event_t event,
                                     coap_session_t *session);
.fi
.if n \{\
.RE
.\}
.sp
Events can be one of the following
.sp
.if n \{\
.RS 4
.\}
.nf
/**
 * (D)TLS events for COAP_PROTO_DTLS and COAP_PROTO_TLS
 */
COAP_EVENT_DTLS_CLOSED        0x0000
COAP_EVENT_DTLS_CONNECTED     0x01DE
COAP_EVENT_DTLS_RENEGOTIATE   0x01DF
COAP_EVENT_DTLS_ERROR         0x0200
/**
 * TCP events for COAP_PROTO_TCP and COAP_PROTO_TLS
 */
COAP_EVENT_TCP_CONNECTED      0x1001
COAP_EVENT_TCP_CLOSED         0x1002
COAP_EVENT_TCP_FAILED         0x1003
/**
 * CSM exchange events for reliable protocols only
 */
COAP_EVENT_SESSION_CONNECTED  0x2001
COAP_EVENT_SESSION_CLOSED     0x2002
COAP_EVENT_SESSION_FAILED     0x2003
.fi
.if n \{\
.RE
.\}
.SH "EXAMPLES"
.sp
\fBGET Resource Callback Handler\fR
.sp
.if n \{\
.RS 4
.\}
.nf
#include <coap2/coap\&.h>

void
hnd_get_time(coap_context_t *context, coap_resource_t *resource,
coap_session_t *session, coap_pdu_t *request, coap_string_t *token,
coap_string_t *query, coap_pdu_t *response) {

  unsigned char buf[40];
  size_t len;
  time_t now;

  /* \&.\&.\&. Additional analysis code for resource, request pdu etc\&.  \&.\&.\&. */

  /* After analysis, generate a suitable response */

  /* Note that token, if set, is already in the response pdu */

  now = time(NULL);

  if (query != NULL && coap_string_equal(query, coap_make_str_const("secs"))) {
    /* Output secs since Jan 1 1970 */
    len = snprintf((char *)buf, sizeof(buf), "%lu", now);
  }
  else {
    /* Output human\-readable time */
    struct tm *tmp;
    tmp = gmtime(&now);
    if (!tmp) {
      /* If \*(Aqnow\*(Aq is not valid */
      response\->code = COAP_RESPONSE_CODE(404);
      return;
    }
    len = strftime((char *)buf, sizeof(buf), "%b %d %H:%M:%S", tmp);
  }
  /*
   * Invoke coap_add_data_blocked_response() to do all the hard work\&.
   *
   * Define the format \- COAP_MEDIATYPE_TEXT_PLAIN \- to add in
   * Define how long this response is valid for (secs) \- 1 \- to add in\&.
   *
   * OBSERVE Option added internally if needed within the function
   * BLOCK2 Option added internally if output too large
   * ETAG Option added internally
   */
  coap_add_data_blocked_response(resource, session, request, response, token,
                                 COAP_MEDIATYPE_TEXT_PLAIN, 1,
                                 len,
                                 buf);

  /*
   * As resource\->code has been updated in coap_add_data_blocked_response(),
   * the response pdu will be transmitted by the underlying library\&.
   */

}
.fi
.if n \{\
.RE
.\}
.sp
\fBPacket Response Handler\fR
.sp
.if n \{\
.RS 4
.\}
.nf
#include <coap2/coap\&.h>

static void
response_handler(coap_context_t *ctx, coap_session_t *session,
coap_pdu_t *sent, coap_pdu_t *received, const coap_tid_t id) {

  coap_pdu_t *pdu = NULL;
  coap_opt_t *block_opt;
  coap_opt_iterator_t opt_iter;
  unsigned char buf[4];
  size_t len;
  unsigned char *databuf;
  coap_tid_t tid;

  /* check if this is a response to our original request */
  if (!check_token(received)) {
    /* drop if this was just some message, or send RST in case of notification */
    if (!sent && (received\->type == COAP_MESSAGE_CON ||
                  received\->type == COAP_MESSAGE_NON))
      coap_send_rst(session, received);
    return;
  }

  if (received\->type == COAP_MESSAGE_RST) {
    info("got RST\en");
    return;
  }

  /* Output the received data, if any */
  if (COAP_RESPONSE_CLASS(received\->code) == 2) {
    /* Additional code to deal with the response */

  }
  return;

}
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
\fBcoap_resource\fR(3)
.SH "FURTHER INFORMATION"
.sp
See "RFC7252: The Constrained Application Protocol (CoAP)" for further information\&.
.SH "BUGS"
.sp
Please report bugs on the mailing list for libcoap: libcoap\-developers@lists\&.sourceforge\&.net
.SH "AUTHORS"
.sp
The libcoap project <libcoap\-developers@lists\&.sourceforge\&.net>
